valmap
3/31/2011

valmap is a command line tool and is my version of a voxel-wise statistical analysis program for images. It assumes that you have a number of images already in spatial correspondence and wish to use a linear model for statistical analysis. No assumptions are made regarding the images to be analyzed...they can be images of gray matter density, jacobian images, etc.

valmap DOES NOT do nonlinear registration...you must use another program to align your images into spatial correspondence.

Only the very simple linear model is implemented, i.e. designs that can be modeled as Y=AB, where Y is a vector or matrix of dependent variables, B is a vector or matrix of parameters to be estimated, and A is a design matrix. See, "Detecting structural changes in whole brain based on nonlinear deformations-application to schizophrenia research," Gaser C, Volz HP, Kiebel S, Riehemann S, Sauer H., Neuroimage. 1999 Aug;10(2):107-13, for a description of the statistical model implemented.

Why would you choose to use valmap?

1. Code in C/C++, so you do not need a Matlab license to run.
2. Can incorporate a spatially varying independent variable (e.g., you have a perfusion map as your dependent variable, and you want to co-vary for gray matter at each voxel, so you can use a gray matter map as an independent variable).
3. Can use spatially invariant independent variables (e.g., you can have a cognitive test score as the dependent variable, and use jacobian maps as the independent variable. NOTE: this is still a voxel-wise analysis).
4. Can have multiple dependent variables and do multivariate analyses (e.g., want to know the overall effect of disease on perfusion and structure, so can have perfusion maps and jacobian maps as dependent variables).

To run valmap, use

valmap input_file output_file

The file input_txt is a text file that lists model parameters, things like number of dependent variables, number of observations (subjects), number of independent variables, whether or not to normalize the data, etc. InputFileStructure.txt (in the doc directory of this distribution) lists the format for the input parameter file. The file output_file keeps a kind of record of the statistical analysis (copy of the design matrix and independent variables, permutation testing thresholds, etc, statistical image files written). I find input_file and output_file nice for record keeping...I then have copies that show the linear model parameters and the statistical maps that were generated from that linear model, so if I have to go back after months, it's easier to figure things out.

I have include a VERY simple java GUI, if you don't like making input files (in valmapGUI\dist\valmapGUI.jar). This GUI simply collects the information needed to create input_file, writes input_file, then calls valmap input_file output_file. The valmap executable should be in the same directory as valmapGUI.jar (or in the path so it can be found). To run at the command line, type

java -jar valmapGUI.jar

I used jdk1.6.0_16 to develop this...if you have trouble running try updating your java installation. I was not able to run it using an older version of gcj, but it ran just fine with new jdk. If jdk is installed under windows, you should be able to just double-click on the .jar file to run.

Image file formats supported are Analyze and Nifti. The nifti 1.1.0 libraries are used to read and write images, so if your file format is not supported by the nifti libraries, valmap won't be able to read it, either.

valmap uses both the nifti 1.1.0 libraries and the blitz-0.9 libraries. You must install these libraries before comiling valmap. These libraries can be found:

http://niftilib.sourceforge.net/

http://www.oonumerics.org/blitz/

NOTE: if you're compiling blitz++ on a newer version of gcc, you must include the line

#include <cstdlib>

in funcs.h and mathfunc.h for blitz++ to compile.

On Linux, valmap was compiled using GNU g++. On a PC, valmap was compiled using MinGW (http://www.mingw.org/). I have not tried using any other compilers on the PC...with effort I'm sure it can be done. I have not tried compiling valmap for the Mac. The netbeans IDE (www.netbeans.org) works very well with mingw or GNU on Linux, so you might want to try that if you're not a command line kind of person (try the java + netbeans bundle if you want to mess around with the very simple java GUI I've created),

http://java.sun.com/javase/downloads/netbeans.html

Makefile will need to be edited with the location of your blitz and nifti installations. Once you've installed the nifti libraries and blitz++ and edited the Makefile, you should be able to compile valmap at the command line:

make valmap

I have played around a little bit with OpenMP (http://openmp.org/wp/) to try to parallelize the code, in order to take advantage or dual and quad core processors. I haven't had much luck. There are a number of OpenMP directives in the code, but I didn't have any luck actually speeding up my code when I parallelized, so I am not using the OpenMP compile flags or linking to the OpenMP libraries. I think perhaps my loops are too small to gain much benefit, but this is something that I haven't explored fully. You can compile with the flag -fopenmp (commented out in the Makefile included) and include the OpenMP library (-lgomp, also commented out in Makefile). If you have any luck speeding things up, please let me know!

WARNING: For processing, I use a linux computer with 8 Gb of RAM. I wrote valmap to read all the images into memory to minimize the amount of time spent on disk access. This is especially important when doing permutation testing for multiple comparisons correction. However, if you are using a computer with only 2 Gb of RAM, you will probably run into some memory limitations and may only be able to run models with relatively few subjects (depending on the dimensions of your images). It should be relatively simple to modify the code to process only some of the image at a time, but I haven't needed to do it yet and so it isn't in this version. If you run into this problem...well, memory is cheap and buying more is probably a better solution than wading your way through my code. But if you do implement this, please let me know and share it!

The directory testImages has a number of images (just two-tone boxes) that can be used to test valmap (and make sure your compilation worked). The directory testValmap has a number of sample input files to test different models (models with images as dependent variables and only static independent variables, models with multiple images as dependent variables, models with spatially varying independent varibles, models with static dependent variables such as a cognitive score, etc.) The file TestFilesExplanation.txt lists the values in the images in testValmap and the correct values for the statistic files from valmap. The folder StatisticalMaps has the correct output for the test input files.

If you run into any problems or have any questions, please contact me. 

Valerie Cardenas Nicolson
valerie.cardenas-nicolson@ucsf.edu